8.7. Capstone

What is the capstone goal?

Create a domain-specific agent platform that preserves the course's open contracts while replacing the fictional Ops Copilot domain with a problem you understand. Examples include a developer-support agent, data-quality investigator, security triage assistant, or internal platform runbook copilot.

Your required path must remain usable with open-source software and the Apache-2.0 open-weight Qwen3 model: no account, no mandatory SaaS, and no usage fee. Optional hosted models or cloud overlays may be added as clearly labelled comparisons, never as hidden requirements.

This is an extension project, not a file-by-file reconstruction exercise. Start from the completed reference on main, create a focused branch, and change one boundary at a time while the existing gates remain green.

What is your starting state?

Before changing the domain, establish a reproducible baseline:

mise install
mise run install
mise run doctor
mise run format
mise run check
mise run test
git status --short

Record the commit you started from and the passing test/coverage summary. Keep the immutable seed/writable state split: committed input is reproducible, runtime state is disposable, and approved writes never dirty the seed.

Run the reference once on direct Ollama before changing behavior:

ollama pull qwen3:4b
mise run doctor:model
cd agents/python
mise run run

Ask one read-only question and save the provider, model, prompt, tool trajectory, and result as your baseline evidence.

Which design decisions must you write down?

Keep the design brief to one page or one pull-request description, but make these decisions explicit:

Prefer the smallest platform that satisfies those answers. Adding another framework, database, broker, vector store, or cloud service is not a capstone achievement unless it removes a demonstrated constraint.

Which files will you normally change?

Use the existing flat ownership boundaries:

Do not rename every file merely to make the project look new. Rename domain language where it improves clarity; preserve stable protocol and task contracts where they already fit.

Which milestones should you deliver?

1. Bound the domain. Replace or extend the fictional seed with sanitized data, define trusted types, and document one useful user outcome plus one case where deterministic code is better than an agent.
2. Implement evidence-backed reads. Add at least one typed read tool and one runbook/skill or retrieval path. Validate identifiers before filesystem/database access and return provenance the model can cite.
3. Implement one guarded write. Require explicit confirmation and rationale, validate the target, commit state plus audit evidence in one transaction, and prove update/delete protection on the audit table.
4. Compose the agent. Update the instruction, structured report, tool registry, budgets, retries, and safe errors. Keep local Ollama as the default provider and keep imports free of network/destructive work.
5. Expose open boundaries. Publish the appropriate reads through MCP, keep writes in-process unless you can preserve confirmation authority, and update A2A discovery for the new capability.
6. Prove behavior. Add deterministic unit/integration tests, adversarial cases, and model-backed evaluation cases that check tool trajectories and grounding rather than prose style alone.
7. Govern the host path. Update the agentgateway MCP allowlist/policies, run the loopback wrapper, and make mise run smoke:host prove MCP, A2A, model, and metrics routes.
8. Deliver locally on Kubernetes. Update the image/manifests, deploy to the shared k3d cluster with kagent, verify private ClusterIP/port-forward access, persistence, probes, quotas, and NetworkPolicies.
9. Close the operations loop. Produce a trace, useful metric/dashboard view, evaluation result, approved-action audit row, and a scoped cleanup procedure.
10. Make it teachable. Update the human and agent documentation so another learner can reproduce the baseline, run one successful path, diagnose a failure, and clean up without private knowledge.

Commit-sized milestones are easier to review and debug than one final rewrite. Keep each milestone green before starting the next.

Which contracts should remain stable?

• AGENT_MODEL_PROVIDER=openai-compatible with direct Ollama at http://127.0.0.1:11434/v1 remains the account-free first run.
• Chapter 5 changes OPENAI_BASE_URL to http://127.0.0.1:4000/v1; provider selection does not double as deployment topology.
• MCP reads use :3000, A2A uses :3001, the model uses :4000, gateway metrics use :15020, and host readiness uses :15021.
• Immutable seed and writable runtime state remain separate.
• State-changing tools require confirmation and append audit evidence atomically.
• Telemetry content capture remains false by default.
• Host listeners are loopback-published through the digest-pinned wrapper; native Linux uses a bridge-scoped relay for loopback backends and Compose's metrics scrape, and Kubernetes services remain private.
• Offline tests never require a model, provider account, cluster, or cloud resource.

You may change a stable contract only when the capstone's outcome requires it. State the incompatibility, migration, updated tests, and learner impact explicitly.

Which gates prove each layer?

A screenshot is supporting evidence, not a gate. Prefer commands, machine-readable output, tests, traces, and artifact digests that another person can reproduce.

What evidence should your final submission contain?

Provide one concise handoff with:

• The user problem, non-goals, and architecture/authority decisions.
• The starting and final Git commit identifiers.
• The selected provider/model/base URL and installed Ollama model ID.
• The deterministic test summary and branch-coverage result.
• The evaluation cases, exact tool-trajectory score, and known model failures.
• A sanitized trace identifier or export showing model, tool, and gateway spans.
• A gateway smoke result and the policies/allowlist added for your tools.
• Kubernetes resources, image digest, readiness result, and proof no public service was created.
• One approved write with its confirmation, state change, and audit row.
• Security-scan results, residual risks, and deliberately absent production controls.
• Cleanup commands and confirmation that disposable processes/resources were stopped.

Do not submit credentials, raw sensitive prompts, private logs, .env, runtime databases, or generated key material.

How is the capstone assessed?

Score the evidence, not the number of tools. A smaller platform with clear authority and reproducible proof should outperform a larger stack with hidden assumptions.

How do you clean up safely?

Stop host processes and the detached gateway:

mise run gateway:host:stop
mise run observability:down
(cd agents/python && mise run data:reset)

For Kubernetes, confirm the context before removing only the capstone workload:

test "$(kubectl config current-context)" = k3d-local
cd infra
skaffold delete -p local

Do not delete a shared cluster, PVC, cloud resource, or generated evidence until you have reviewed its ownership and retention requirement. An optional GCP plan creates nothing; any approved apply needs a separately reviewed destroy and cost check.

What is the capstone checkpoint?

Ask another person to follow your documented path from a clean authorized clone. They must be able to pass the base gate, run one grounded local-model request, exercise the governed host route, inspect your evidence, and clean up without asking you for an undocumented credential or step.

Your capstone is complete when that handoff succeeds and the final diff still passes:

mise run format
mise run check
mise run test
mise run scan
git status --short